Introduction

This pull request introduces support for infix catch-all wildcard parameters, enhancing the routing flexibility. Developers can now define routes with catch-all parameters (*{param}) not only at the end but also in the middle of the route path. This allows for more dynamic and versatile URL matching patterns, catering to a wider range of application requirements.

Background and Motivation

Previously, the router supported:

• Named Parameters: {param} matching exactly one non-empty path segment.
• Catch-All Parameters: *{param} matching zero or more segments, but only at the end of a route path.

This limitation restricted the ability to define routes that require matching variable-length path segments within the middle of a URL. Infix catch-all parameters allow for more complex and descriptive routing patterns, such as /*/track (a feature needed for Wiztrack that was not supported by gin).

Breaking Change

One subtle breaking change has been introduced: catch-all wildcards no longer match empty segments, including at the end of a route. All matches now have to be explicit. However, it's now possible to define routes such as /path/ and /path/*{any} to reproduce the same empty match behavior (which was previously not allowed).

Handling Empty Segments

To match both routes with and without additional path segments, you can register two routes:

// Matches the path with no additional segments
f.Handle("GET", "/path/", handlerForEmpty)

// Matches the path with one or more additional segments
f.Handle("GET", "/path/*{any}", handlerForCatchAll)

This explicit approach ensures that you only handle empty segments when you intend to.

Security Consideration

A common scenario is serving static content using a route like /static/*{filepath}. In many routers (e.g., standard http.ServeMux, Gin, Echo), this route matches empty segments by default, potentially allowing directory listing, of the base folder which can be a security concern.

By not matching empty segments with catch-all wildcards, we can at least prevents unintended directory listing.

Future Considerations

Serving static files and handling directory listings are common needs. In the future, we plan to introduce an API helper to simplify serving static content.

Infix Wildcards

Catch-all wildcards can now be placed anywhere in the path, not just at the end.

Example:

Pattern: /assets/*{path}/thumbnail

- /assets/images/thumbnail           matches, {path} = "images"
- /assets/photos/2021/thumbnail      matches, {path} = "photos/2021"
- /assets//thumbnail                 does not match (empty {path} not matched)

They can also be followed or preceded by named parameters. For example, /foo/*{bar}/{baz} is valid and allows for flexible route definitions.

Note: Catch-all wildcards cannot be consecutive. For example, /foo/*{any1}/*{any2} is not allowed. Since catch-all wildcards match at least one segment, the above pattern is equivalent to /foo/{param}/*{catchAll}, which is allowed and more explicit about which segment matches each parameter.

Differential Benchmark

goos: linux
goarch: amd64
pkg: github.com/tigerwill90/fox
cpu: Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
                    │   old.txt   │               new.txt                │
                    │   sec/op    │    sec/op     vs base                │
StaticAll-16          11.28µ ± 4%    12.14µ ± 6%   +7.63% (p=0.000 n=10)
GithubParamsAll-16    75.66n ± 2%    84.42n ± 3%  +11.58% (p=0.000 n=10)
OverlappingRoute-16   91.59n ± 1%    96.75n ± 2%   +5.63% (p=0.000 n=10)
StaticParallel-16     9.582n ± 5%   10.740n ± 2%  +12.09% (p=0.000 n=10)
CatchAll-16           31.39n ± 6%    35.53n ± 2%  +13.19% (p=0.000 n=10)
CatchAllParallel-16   5.973n ± 5%    5.737n ± 8%        ~ (p=0.289 n=10)
CloneWith-16          63.58n ± 2%    69.98n ± 1%  +10.07% (p=0.000 n=10)
geomean               70.82n         76.40n        +7.89%